<h1>Handling Successful Requests</h1>
<p>
  The <code>mx-on-success</code> attribute lets you trigger elements after an HTTP request has been made and a response code within the success range has been received.  This makes it possible for one action (such as the submission of a form) to result in several different parts of a page being updated.</p>

<div class="alert alert-warning">
  <p>The <code>mx-on-success</code> attribute (which happens to be the focus of this page) is designed for reinitialising elements, <b>not</b> for executing custom JavaScript!</p>

  <p>To execute your own custom JavaScript code after an HTTP request, use the <code>mx-after-swap</code> attribute. You can find the relevant documentation <a href="documentation/display/trongate_mx/swapping-content/after-swap-operations">here</a>.</p>
</div>


<h2>Syntax</h2>

<p>When working with <code>mx-on-success</code>, we should assign a CSS selector value to indicate which 
  element should be updated (i.e., <b>triggered</b>) after a successful request.
</p>

[code=vf]&lt;element mx-on-success="#target-element"&gt;[/code]

<h2>How It Works</h2>
<p>
  When Trongate MX completes an AJAX request successfully, here's what happens:
</p>
<ol>
  <li>Trongate MX checks the element (that invoked the HTTP request) for an <code>mx-on-success</code> attribute.</li>
  <li>If an <code>mx-on-success</code> attribute is found, the value that has been assigned to the attribute is read.</li>
  <li>Trongate MX identifies an element whose CSS selector matches the value of <code>mx-on-success</code>.</li>
  <li>Any <a href="documentation/display/trongate_mx/core-http-operations/http-methods-in-trongate-mx">HTTP requests  tied to the target element</a> are triggered, reinitialising it.</li>
</ol>
<p>
  This makes it easy to refresh multiple, dynamic sections of your application or set up chained actions.
</p>

<div class="alert alert-info">
  <p>Throughout this documentation, you'll see phrases like:</p>
  <ul>
    <li>"receives a response within the 'success' range"</li>
    <li>"completes an AJAX request successfully"</li>
  </ul>
  <p>Whenever you see phrases like that, it's usually a reference to the <b>HTTP response status code</b> that has been received from an API endpoint.</p>

<p><strong>Success Range (2xx)</strong></p> 
<p>HTTP response status codes within the range of <b>200-299</b> indicate that the request was successful.</p> 
<p>Common examples include:
    <ul>
        <li>200 OK: Request was successful and data is returned.</li>
        <li>201 Created: A new resource has been created.</li>
        <li>204 No Content: Request was successful but no content is returned.</li>
    </ul>
  </p>
</div>

<h2>Example</h2>
<p>In the following example, we have a form that submits a POST request to an API endpoint.</p> 

<p>When a response is received from the server that has an HTTP response status code within the success range, a <code>&lt;div&gt;</code> element with an "id" of "order-summary" is triggered.</p>  
<p>Since the targetted element has an <code>mx-get</code> attribute, a second HTTP request will immediately be made. Specifically, this will be a GET request to the target URL of 'api/get_order_summary'.</p>

[code=vf]
&lt;?php
$form_attr = [
    'mx-post' =&gt; 'api/submit_order',
    'mx-target' =&gt; '#order-confirmation',
    'mx-on-success' =&gt; '#order-summary'
];
echo form_open('#', $form_attr);
echo form_submit('submit', 'Place Order');
echo form_close();
?&gt;
&lt;div id="order-confirmation"&gt;&lt;/div&gt;
&lt;div id="order-summary" mx-get="api/get_order_summary" mx-trigger="load"&gt;
  &lt;!-- Order summary content --&gt;
&lt;/div&gt;
[/code]

<p class="mt-3 mb-0">Since the usage of Trongate's form helper functions is optional, here's an alternative syntax that uses pure HTML:</p>

[code=html]
&lt;form mx-post="api/submit_order"
      mx-target="#order-confirmation"
      mx-on-success="#order-summary"&gt;

    &lt;button type="submit"&gt;Place Order&lt;/button&gt;
&lt;/form&gt;

&lt;div id="order-confirmation"&gt;&lt;/div&gt;
&lt;div id="order-summary" mx-get="api/get_order_summary" mx-trigger="load"&gt;
  &lt;!-- Order summary content --&gt;
&lt;/div&gt;
[/code]

<h2 class="mt-3">Understanding The Code</h2>
<p>The example above demonstrates a common code pattern.  It's therefore worth taking a few moments to understand how it works.  Don't worry if the example above seems overwhelming at first.  It'll become clearer with patience and a little practice!</p>
<h3>So, what's the point?</h3>
<p>To be clear, the goal we're trying to achieve - with this code - is as follows:</p>


<p><b>We're trying to update multiple different parts of a page after an HTTP request - made by Trongate MX - has been successfully completed.</b></p>
<hr>

<h3>Why does this matter?</h3>
<p>Having the ability to update <i>multiple</i> different parts of a page, without refreshing the entire page allows us to build extremely powerful applications.  It's the kind of advanced functionality that we might expect to find on <a href="https://wrapbootstrap.com/category/templates/admin-templates" target="_blank">sophisticated admin panels</a> that get used in business.</p>
<hr>

<h3>Do we <i>really</i> need Trongate MX for this?</h3>
<p>Of course we don't!  However, without Trongate MX you'd have to either:</p>
<ol>
  <li>Writes lots of custom JavaScript code.</li>
  <li>Refresh the entire page every time an update happens.</li>
  <li>Use a JavaScript framework that might get rewritten tomorrow!</li>
</ol>

<p>Surely you'll agree, none of those three options are ideal - particularly if you're trying to build a modern application quickly and with massive degrees of stability.</p>

<div class="alert alert-info">
<p>By the way, if you're still not sold on Trongate MX - just imagine a stock market trading website where you had to manually refresh the entire page every time a stock price changed.  Such an application would be considered to be hopelessly old-fashioned and perhaps even useless!</p>
<p>This is why Trongate MX is a really important tool for the Trongate ecosystem.  It lets you build modern web applications quickly and easily.</p>
</div>

<h3 class="mt-3">How does the code example above work?</h3>

<p>The best way to understand the code example, shown above, is to start from the bottom and work our way up. So, let's consider this element:</p>

[code=html]
&lt;div id="order-summary" mx-get="api/get_order_summary" mx-trigger="load"&gt;
  &lt;!-- Order summary content --&gt;
&lt;/div&gt;
[/code]

<p>The element above is an empty div with an id of 'order-summary'. If you look closely, you'll see that the div contains an attribute of <code>mx-trigger</code> with a value of '<b>load</b>'. From this, we know that the element is going to be triggered the moment the page has finished loading.</p>
<p>Have a closer look and you'll notice that the '#order-summary' div also has an <code>mx-get</code> attribute with a value of 'api/get_order_summary'.</p>
<p>From this, we now know that as soon as the page loads, a GET request will be made and (if all goes well!) order details will be added inside the '#order-summary' element.</p>

<div class="alert alert-success">
  <p>If the behaviour of the #order-summary element is confusing, you are encouraged to refer to our section on <a href="documentation/display/trongate_mx/events-and-responses/triggers-in-trongate-mx">Triggers In Trongate MX</a>.</p>
</div>

<p>Moving up, we see another div element:</p>

[code=html]
&lt;div id="order-confirmation"&gt;&lt;/div&gt;
[/code]

<p>This empty div with an id of 'order-confirmation' will be used to display the response from our form submission. Notice that it doesn't have any Trongate MX attributes of its own - it's simply a target for our server response.</p>

<p>You may wonder,</p>
<p>"What <i>is</i> the server response going to be?"</p>

<p>Good question!</p>

<p>Well... it could be something as simple as some text containing the words,</p>

<code>The order was successfully updated.</code>
<p>It's no big deal and perhaps <i>not</i> as complicated as you may have assumed!</p>
<h3 class="mt-3">The Form Structure</h3>
<p>Now let's examine the form, in our example:</p>

[code=php]
$form_attr = [
    'mx-post' =&gt; 'api/submit_order',
    'mx-target' =&gt; '#order-confirmation',
    'mx-on-success' =&gt; '#order-summary'
];
echo form_open('#', $form_attr);
[/code]

<p>This form has three important Trongate MX attributes:</p>
<ol>
    <li><code>mx-post</code>: When the form is submitted, it will make a POST request to 'api/submit_order'.</li>
    <li><code>mx-target</code>: The response from this POST request will be displayed in the '#order-confirmation' div.</li>
    <li><code>mx-on-success</code>: If the POST request is successful (returns a 2xx status code), the '#order-summary' div will be triggered.</li>
</ol>

<h3 class="mt-3">The Complete Flow</h3>
<p>Now that we understand each piece, here's how it all works together:</p>
<ol>
    <li>When the page first loads, the '#order-summary' div is automatically triggered (due to <code>mx-trigger="load"</code>), making a GET request to fetch and display the initial order summary.</li>
    <li class="mt-1">When a user clicks the "Place Order" button, the form submits a POST request to 'api/submit_order'.</li>
    <li class="mt-1">The response from this POST request is displayed in the '#order-confirmation' div.</li>
    <li class="mt-1">If the POST request was successful, the '#order-summary' div is triggered again.</li>
    <li class="mt-1">This trigger causes another GET request to 'api/get_order_summary', refreshing the order summary with the latest data.</li>
</ol>

<h2>Why This Pattern Is Useful</h2>
<p>This pattern is particularly helpful when you need to update multiple elements after a successful form submission. The initial form submission can return a success message, while the triggered element can fetch and display updated data without requiring a full page reload.</p>

<div class="alert alert-info"> <p>If you look closely at the code example above, you might notice a hash ('#') symbol being passed into the <span class="feature-ref" ref-path="helpers/Form_Helpers">form_open()</span> function as an argument. This might seem unusual since the first argument is typically expected to be the target URL where the form will post.</p> <p>The hash symbol is used here because the <code>mx-post</code> attribute overrides any 'action' or 'method' properties that would normally be found in a standard form opening tag.</p>
</div>

<h2>Working With Pure HTML</h2> 
<p>As a reminder, you're not obligated to use Trongate's form helper functions when working with Trongate MX. If you prefer to work with pure HTML, the following code could be used:</p>

[code=html]&lt;form mx-post="api/submit_order" 
      mx-target="#order-confirmation" 
      mx-on-success="#order-summary"&gt; 
    &lt;button type="submit"&gt;Place Order&lt;/button&gt; 
&lt;/form&gt;

&lt;div id="order-confirmation"&gt;&lt;/div&gt;

&lt;div id="order-summary" mx-get="api/get_order_summary" 
                        mx-trigger="load"&gt;&lt;/div&gt; [/code]


<h2>Things to Keep in Mind</h2>
<ul>
  <li><code>mx-on-success</code> only works for client-side handling of successful AJAX requests.</li>
  <li>It won't affect elements during the initial page load.</li>
</ul>
